Amiga Plus 2000 #5

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Plus 2000 #5 / Amiga Plus CD - 2000 - No. 5.iso / Tools / Grafik / Misc / netpbm / README < prev next >

Wrap

Text File | 2000-01-01 | 27.3 KB | 633 lines

N E T P B M Release 9.6 Netpbm is a toolkit for conversion of images between a variety of different formats, as well as to allow a few basic image operations. The package is intended to be portable to many platforms. It has, at least at one time, been tested under various Unix-based systems, VMS and Amiga OS. There are also compiler directives in it for MS-DOS. The maintainer uses and builds it on a platform that consists (in relevant part) mainly of GNU software (you probably know this kind of system by the name "Linux"). There are over 180 separate tools in the package. The idea behind Netpbm is to define 3 very basic (and inefficient) portable graphics formats: PBM for black and white, PGM for grayscale, and PPM for color. These are collectively referred to as PNM. To convert from one common graphics format to another, you use a PNM format as an intermediate format. So if you want to convert among N image formats, you only need 2*N conversion filters, instead of the N^2 you would need if you wrote each conversion tool separately. In addition to the converters, the package includes some simple tools for manipulating the portable formats. For example, you can shrink an image or cut the top 10% off or make a mirror image. Among the 3 PNM formats, the Netpbm tools are are upwards compatible: A program to read PGM files will also read a PBM file, and a program to read PPM files reads all three. The image editing programs usually write the same type as they read. Whenever a program makes an exception and "promotes" a file to a higher format, it lets you know. The goal of Netpbm is to be a single source for all the primitive graphics utilities, especially converters, one might need. So if you know of some freely redistributable software in this vein which is not in the package yet, you should bring it to the attention of the Netpbm maintainer so it can be included in the next release. Netpbm replaces the widely spread Pbmplus package (release: 10 Dec 91). A lot of improvements and additions have been made. After the latest release of pbmplus, a lot of additional filters began circulating on the net. The aim of Netpbm was to collect these and to turn them into a package. This work has been performed by programmers all over the world. If *you* have some code to add, please contact the Netpbm maintainer. DISTRIBUTION ------------ You'll find the latest release of Netpbm source code at <http://download.sourceforge.net/netpbm/>. A prebuilt version for Cygwin is at <ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters> Contact Pierre A. Humblet <Pierre.Humblet@ieee.org>. PREREQUISITES ------------- Don't sweat the prerequisites too much. In most cases, if you're missing something, the build of the programs that depend on it will bomb, but the rest of the Netpbm programs will build just fine. And you may not need the more demanding programs. If you have trouble getting, building, or installing the prerequisites, the Netpbm maintainer wants to know. Since he uses them himself, he can help you. And if there is a problem with a prerequisite package that its own maintainer cannot fix, it may be possible to ship a fix with Netpbm. Ordinarily, the Tiff library would be a prerequisite for building the Tiff tools, but we have included a complete version of the Tiff library in Netpbm. The main reason we did this is to make it easier for you to build, particularly in a way compatible with Netpbm. The automatic configuration tool that comes with the regular distribution of the library has bugs. The official source for the Tiff library is http://www.libtiff.org. To build ppmtojpeg or jpegtoppm, you need the JPEG/JFIF library from the Independent JPEG Group (IJG). You can get it at ftp://ftp.uu.net/graphics/jpeg. See http://www.ijg.org for more information. You need Release 6 or better. With Release 5, Netpbm build fails with undefined jpeg symbols. If you want the tiff programs to be able to deal with JPEG-compressed tiff files, you need the jpeg library (above). If you don't have the jpeg library, you must specify so in Makefile.config or you won't be able to build the tiff tools at all. The same goes for ppmtompeg. You need the jpeg library if you want to create mpegs from jpegs (without the loss of quality that comes with converting from jpeg to ppm first), and if you don't have the jpeg library and don't say so in Makefile.config, you won't be able to build ppmtompeg at all. To build or use pnmtopng and pngtopnm, you need the zlib compression library and the png library (libpng). You can get zlib from ftp://quest.jpl.nasa.gov/pub/zlib or ftp://metalab.unc.edu/pub/Linux/libs. You can get libpng from ftp://ftp.au.netbsd.org/pub/NetBSD/packages/distfiles. Pstopnm (the Postscript to PNM image converter) requires Ghostscript (installed with the name 'gs' in your command search path). And it requires in particular that Ghostscript be built with the relevant PNM device drivers. See http://www.gnu.org/ghostscript/ . The Utah Raster Toolkit is not a prerequisite because Netpbm includes a subset of it that meets the needs of pnmtorle and rletopnm. However, you can also substitute the real package by properly configuring Makefile.config. You can get it from ftp://ftp.cs.utah.edu/pub/dept/OLD/pub/urt-3.1b.tar.Z. There's a patch at ftp://ptolemy.berkeley.edu/pub/misc/urt/urt-3.1b-3.1b1.patch INSTALLATION ------------ If you are building Netpbm on and for a typical system running GNU tools and libc (as virtually any system that uses the Linux kernel is), you can just do: make To build all the programs. Then make install to install them all. The only tricky part about installing is setting up the shared libraries that are part of Netpbm. 'make install' copies them into place, but that may not be enough. If you get mysterious "file not found" kinds of errors and are not an expert with shared libraries, see the section "SHARED LIBRARIES" below. You may want to append the contents of the file 'magic' to your 'file' database (typically /etc/magic). This allows the 'file' program to recognize a bunch of file formats, including the Netpbm formats. If you don't need the whole package, but just want one tool in it that you heard about, you can make just that one. For example, to make ppmtojpeg, just cd to the ppm directory and run make ppmtojpeg STATICLIB=Y . It will build ppmtojpeg and any of its dependencies, but nothing else. You have to install it manually. We set the STATICLIB variable because if you're building just one program, the shared libraries would be pure masochism. The --keep-going option to Make is handy, because it causes Make to make anything it can, as opposed to quitting as soon as something goes wrong. With so many parts having so many requirements, it's not unusual for a few things to fail to build, but that doesn't affect everything else. You can work on the failed parts and repeat the make and it will attempt to build whatever it hasn't successfully built yet. INSTALLATION - NOT GNU - SOLARIS, SUNOS, NETBSD, CYGWIN, BEOS, TRU64 -------------------------------------------------------------------- Unless you want to do some make file rewriting, you will need to use GNU Make even if nothing else on your system is GNU, because the Netpbm make files exploit some advanced features of GNU Make. Often, systems have both GNU Make and a native Make. In this case, GNU Make is named 'gmake'. If you don't have it yet, see www.gnu.org/software. GNU Make is free, easy to install, and works just about anywhere. If the standard make files don't work on your platform, then update Makefile.config. This file contains settings for various things that vary from one system to the next, like file paths. Search for your platform name (Solaris, SunOS, NetBSD, Cygwin, BeOS, and Tru64 are mentioned) to see recommended settings for your platform. If you've messed up Makefile.config and need to start over, Makefile.config.in is a copy of the distributed version of Makefile.config. If your system is even too exotic for that, you may need to modify things in the main make files or pbmplus.h. If you figure out how to install on other platforms, contact the Netpbm maintainer to have these instructions improved for the next person. INSTALLATION - MISCELLANEOUS ---------------------------- After installing the manual pages, you may want to create the "whatis" file by doing a catman -w -M <directory>, or makewhatis -w, or whatever the equivalent is on your system. Without Whatis, you may have a hard time finding the Netpbm tools you have installed. There is a patch to Zgv 5.0 to allow it to work with the newer Netbpm formats with maxval > 255. If you have Zgv 5.1 or later, you don't need it. The patch is in the Netpbm source directory as zgv_bigmaxval.patch. Zgv is a graphics file viewer. See below. INSTALLATION - SHARED LIBRARIES ------------------------------- There are over 180 programs in the Netpbm package and they do a lot of common things. In order to avoid the expense of copying the code for those common things into every program, Netpbm places it in 4 shared libraries: libpbm, libpgm, libppm, and libpnm. There is also a libtiff shared library that comes with Netpbm. When you invoke a Netpbm program, your system notices that it needs these libraries and accesses them too. The tricky part of installing the shared (runtime) libraries is telling your system where to find them in the event that you invoke a Netpbm program. And that varies from one system to the next. On a GNU libc system (essentially, any Linux-based system), if you put the Netpbm shared libraries in a conventional spot (say, /lib) and reboot your system, chances are you will have no trouble running Netpbm programs. But if you want to fine tune things, read up on ld-linux.so (GNU libc's dynamic linker) and ldconfig and consider the /etc/ld.so.conf file and LD_LIBRARY_PATH environment variables. Use 'ldd' to see if you have a shared library issue. If it shows any shared library as "not found", you've got library trouble. One final note: New Netpbm executables often can run OK with old Netpbm shared libraries. This means if you don't correctly install the new libraries, you may run what you think is a new Netpbm program, but in actuality be accessing the old Netpbm library, and you may not even notice a problem right away. But eventually, you may find some things not working the way they should. Again, 'ldd' will give you peace of mind. HOW TO FIND THE RIGHT CONVERTER ------------------------------- Some people get confused by all the different names. If you want to convert a pbm file to a Sun raster file, is it pbmtorast, pgmtorast, ppmtorast, or pnmtorast? A useful tool for answering this question, if you have it configured, is man -k. You say "man -k <keyword>" and it gives you all the one-line descriptions with that keyword in them. All the Netpbm man pages have nice useful one-line descriptions, that mention all the relevant keywords. Try it, you'll like it. Here is a brief directory of the Netpbm tools. A "pgmtoxxx" tool accepts PBM as well as PGM input and likewise a "ppmtoxxx" tool accepts PBM, PGM, and PPM. But a "xxxtopgm" tool always creates a PGM file and a "xxxtoppm" tool always creates a PPM file. A "pnmtoxxx" tool accepts all three input formats and behaves differently according to which it is. A "xxxtopnm" tool creates any of two or more of the formats, depending on input and command line options. CONVERTERS ppmtompeg convert series of ppm frames to an mpeg movie jpegtopnm convert JFIF/JPEG file to Netpbm format anytopnm convert any graphics format to Netpbm format ppmtojpeg convert PPM to JPEG/JFIF format bmptoppm convert Windows or OS/2 Bitmap file to PPM ppmtobmp convert PPM to Windows or OS/2 Bitmap file giftopnm convert GIF to portable anymap ppmtogif convert PPM to GIF pnmtopng convert portable anymap to Portable Network Graphics pngtopnm convert Portable Network Graphics to portable anymap jbigtopbm convert JBIG BIE (compressed bitmap) to PBM pbmtojbig convert PBM to JBIG BIE (compressed bitmap) pnmtofiasco convert Netpbm image to Fiasco (wfa) highly compressed format fiascotopnm convert Fiasco (wfa) highly compressed format to Netpbm image hpcdtoppm convert photo CD to PPM pbmtowbmp convert PBM to WAP (Wireless App Protocol) Wireless Bitmap wbmptopbm convert WAP (Wireless App Protocol) Wireless Bitmap to PBM pbmtomda convert from PBM to Microdesign (for Amstrad PCWs) mdatopbm convert from Microdesign (for Amstrad PCWs) to PBM atktopbm convert Andrew Toolkit raster object to PBM pbmtoatk convert PBM to Andrew Toolkit raster object brushtopbm convert Xerox doodle brushes to PBM cmuwmtopbm convert CMU window manager format to PBM g3topbm convert Group 3 FAX to PBM pbmtog3 convert PBM to Group 3 FAX icontopbm convert Sun icon to PBM pbmtoicon convert PBM to Sun icon gemtopnm convert GEM .img format to PBM or pixmap macptopbm convert MacPaint to PBM pbmtomacp convert PBM to MacPaint mgrtopbm convert MGR format to PBM pbmtomgr convert PBM to MGR format pi3topbm convert Atari Degas .pi3 to PBM pbmtopi3 convert PBM to Atari Degas .pi3 xbmtopbm convert X10 or X11 bitmap to PBM pbmtoxbm convert PBM to X11 bitmap pbmtox10bm convert PBM to X10 bitmap ybmtopbm convert Bennet Yee "face" file into PBM pbmtoybm convert PBM into Bennet Yee "face" file pbmto10x convert PBM to Gemini 10x printer graphics pbmtoascii convert PBM to ASCII graphic form asciitopgm convert ASCII character graphics to portable graymap pbmtobbnbg convert PBM to BBN BitGraph graphics pbmtocmuwm convert PBM to CMU window manager format pbmtoepson convert PBM to Epson printer graphics pbmtogem convert PBM into GEM .img file pbmtogo convert PBM to GraphOn graphics pbmtolj convert PBM to HP LaserJet graphics pbmtoplot convert PBM into Unix plot(5) file pbmtoptx convert PBM to Printronix graphics pbmtozinc convert PBM to Zinc Interface Library icon fitstopnm convert FITS format to portable anymap pnmtofits convert portable anymap to FITS format fstopgm convert Usenix FaceSaver(tm) format to portable graymap pgmtofs convert portable graymap to Usenix FaceSaver(tm) format hipstopgm convert HIPS format to portable graymap lispmtopgm convert a Lisp Machine bitmap file into pgm format pgmtolispm convert a portable graymap into Lisp Machine format psidtopgm convert PostScript "image" data to portable graymap rawtopgm convert raw grayscale bytes to portable graymap pgmtopbm convert portable graymap to PBM pbmmask create a mask bitmap from a regular bitmap ppmcolormask create mask of areas of a certain color in an image gouldtoppm convert Gould scanner file to PPM ilbmtoppm convert IFF ILBM to PPM ppmtoilbm convert PPM to IFF ILBM imgtoppm convert Img-whatnot to PPM mtvtoppm convert MTV ray-tracer output to PPM pcxtoppm convert PC Paintbrush format to PPM pgmtoppm colorize a portable graymap into a PPM pi1toppm convert Atari Degas .pi1 to PPM ppmtopi1 convert PPM to Atari Degas .pi1 picttoppm convert Macintosh PICT to PPM ppmtopict convert PPM to Macintosh PICT pjtoppm convert HP PaintJet file to PPM ppmtopj convert PPM to HP PaintJet file qrttoppm convert QRT ray-tracer output to PPM rawtoppm convert raw RGB bytes to PPM rgb3toppm combine three portable graymaps into one PPM ppmtorgb3 separate a PPM into three portable graymaps sldtoppm convert an AutoCAD slide file into a PPM spctoppm convert Atari compressed Spectrum to PPM sputoppm convert Atari uncompressed Spectrum to PPM tgatoppm convert TrueVision Targa file to PPM ppmtotga convert PPM to TrueVision Targa file ximtoppm convert Xim to PPM xpmtoppm convert XPM format to PPM ppmtoxpm convert PPM to XPM format yuvtoppm convert Abekas YUV format to PPM eyuvtoppm convert Encoder/Berkeley YUV format to PPM ppmtoeyuv convert PPM to Encoder/Berkeley YUV format ppmtoyuv convert PPM to Abekas YUV format ppmtoyuvsplit convert PPM to 3 subsampled raw YUV files yuvsplittoppm merge 3 subsampled raw YUV files to one PPM ppmtoacad convert PPM to AutoCAD database or slide ppmtoicr convert PPM to NCSA ICR graphics ppmtopcx convert PPM to PC Paintbrush format ppmtopgm convert PPM to portable graymap ppmtopuzz convert PPM to X11 "puzzle" file ppmtosixel convert PPM to DEC sixel format ppmtouil convert PPM to Motif UIL icon file rasttopnm convert Sun raster file to portable anymap pnmtorast convert portable anymap to Sun raster file tifftopnm convert TIFF file to portable anymap pnmtotiff convert portable anymap to TIFF RGB file pnmtotiffcmyk convert portable anymap to TIFF CMYK file xwdtopnm convert X10 or X11 window dump to portable anymap pnmtoxwd convert portable anymap to X11 window dump pnmtops convert portable anymap to Postscript pstopnm convert Postscript to portable anymap pnmtoplainpnm convert a regular portable anymap into plain pnm format pbmtoepsi convert a PBM image to encapsulated Postscript preview bitmap pbmtopgm convert PBM file to PGM by averaging areas sbigtopgm convert Santa Barbara Instrument Group CCD file to PGM vidtoppm convert Parllax XVideo JPEG to sequence of PPM files pnmtorle convert PNM to Utah Raster Toolkit (urt/rle) file rletopnm convert Utah Raster Toolkit (urt/rle) file to PNM ppmtoleaf convert PPM to Interleaf leaftoppm convert Interleaf to PPM IMAGE GENERATORS pbmmake create a blank PBM image of a specified size ppmmake create a pixmap of a specified size and color ppmpat create a pretty pixmap pgmnoise create a portable graymap of white noise pbmtext render text into a PBM image pbmupc create a Universal Product Code PBM image ppmcie generate a CIE color map image pbmpage create a printer test pattern page. IMAGE EDITORS ppmlabel Add text to an image pnmshadow add a shadow to an image so it looks like it's floating ppmbrighten brighten or dim an image -- change saturation and value ppmdim dim a PPM image - different way from ppmbrighten pbmreduce reduce a PBM N times, using Floyd-Steinberg pgmnorm normalize contrast in a portable graymap image ppmnorm normalize contrast in a PPM image pbmpscale englarge a PBM image with edge smoothing pnmscale scale a portable anymap image ppmdither ordered dither for color images ppmquant quantize colors in an image down to a specified number ppmquantall quantize colors down to a specified number on many files ppmrelief run a Laplacian Relief filter on a PPM pnmarith perform arithmetic on two portable anymaps pnmcat concatenate portable anymaps pnmpad add borders to a portable anymap pnmcomp create composite (overlay) of two portable anymap images ppmmix mix (overlay) two images. pnmcrop crop all like-colored borders off a portable anymap pnmcut select a rectangular region from a portable anymap pnmdepth change the maxval in a portable anymap pnmenlarge enlarge a portable anymap N times pnmflip perform one or more flip operations on a portable anymap pnminterp scale up portable anymap by interpolating between pixels pnminterp-gen scale by non-integer values using pnminterp and pnmscale pnminvert invert a portable anymap pnmgamma perform gamma correction on a portable anymap pnmmargin add a margin to a portable anymap pnmpaste paste a rectangle into a portable anymap pnmrotate rotate a portable anymap pnmshear shear a portable anymap pnmsmooth smooth a portable anymap image pnmtile replicate a portable anymap into a specified size pbmclean remove lone pixels (snow) from a PBM image pnmalias antialias a portable anymap image ppmchange change all of one color to another in PPM image ppmshift shift lines of PPM image left or right a random amount ppmspread move pixels of PPM image a random amount pnmconvol general MxN convolution on a portable anymap pbmlife apply Conway's rules of Life to a PBM image ppmdist map colors to high contrast grayscales arbitrarily ppmntsc adjust colors so they are legal for NTSC or PAL television IMAGE ANALYZERS pnmfile describe a portable anymap pnmpsnr measure difference between two images pgmedge edge-detect a portable graymap pgmenhance edge-enhance a portable graymap pgmramp generate a grayscale ramp pgmslice print grayscale values for a row or column of a pgm image pgmtexture calculate textural features on a portable graymap pgmhist print a histogram of the values in a portable graymap ppmhist print a histogram of a PPM ppmtomap generate a map of all colors in an image MISCELLANEOUS pnmsplit split a multi-image PNM file into multiple 1-image files pnmindex build a visual index of a bunch of anymaps pgmbentley Bentleyize a portable graymap pgmcrater create cratered terrain by fractal forgery pgmoil turn a portable graymap into an oil painting ppmforge fractal forgeries of clouds, planets, and starry skies pgmkernel generate a convolution kernel ppmtv Make an image lined so it looks like an old TV UNCATALOGUED AS YET bioradtopgm pbmto4425 pbmtoln03 pbmtolps pbmtopk pktopbm pnmhisteq pnmhistmap pnmnlfilt pnmtoddif pnmtosgi pnmtosir ppm3d ppmflash ppmqvga ppmtomitsu ppmtopjxl sgitopnm sirtopnm spottopgm xvminitoppm zeisstopnm APPLICATION NOTES ----------------- As a collection of primitive tools, the power of Netpbm is multiplied by the power of all the other unix tools you can use with them. These notes remind you of some of the more useful ways to do this. Often, when people want to add high level functions to the Netpbm tools, they have overlooked some existing tool that, in combination with Netpbm, already does it. Often, you need to apply some conversion or edit to a whole bunch of files. As a rule, Netpbm programs take one input file and produce one output file, usually on Standard Output. This is for flexibility, since you so often have to pipeline many tools together. Here is an example of a shell command to convert all your of PNG files (named *.png) to JPEG files named *.jpg: for i in *.png; do pngtopnm $i |ppmtojpeg >`basename $i .png`.jpg; done Or you might just generate a stream of individual shell commands, one per file, with awk or perl. Here's how to brighten 30 YUV images that make up one second of a movie, keeping the images in the same files: ls *.yuv \ | perl -ne 'chomp; print "yuvtoppm $_ | ppmbrighten -v 100 | ppmtoyuv >tmp$$.yuv;", "mv tmp$$.yuv $_\n" ' \ | sh The tools Find (with the '-exec' option) and Xargs are also useful for simple manipulation of groups of files. Some shells' "process substitution" facility can help where a non-Netpbm program expects you to identify a disk file for input and you want it to use the result of a Netpbm manipulation. Say printcmyk takes the filename of a Tiff CMYK file as input and what you have is a PNG file abc.png. Try: printcmyk <({ pngtopnm abc.png | pnmtotiffcmyk ; }) It works in the other direction too, if you have a program that has you name its output file and you want the output to go through a Netpbm tool. SUPPORT ------- The maintainer of Netpbm, since September 1999, is Bryan Henderson: bryanh@giraffe-data.com. Or as a backup, bryanh@home.com. Bryan actively maintains the package and wants to know about any problems people have with Netpbm or suggestions for improvement. OTHER GRAPHICS SOFTWARE ----------------------- Netpbm contains primitive building blocks. It certainly is not a complete graphics library. The first thing you will need to make use of any of these tools is a viewer. Zgv is a good viewer to use on a GNU/Linux system with the SVGALIB graphics display driver library. You can find Zgv at ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers. Zgv even has a feature in it wherein you can visually crop an image and write an output file of the cropped image using pnmcut. See the -s option to Zgv. For the X inclined, there is also Xzgv. See ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X. ImageMagick is like a visual version of Netpbm. Using the X/Window system on Unix, you can do basic editing of images and lots of format conversions. The package does include at least some non-visual tools, e.g. the Convert program, designed to be invoked from a command shell. ImageMagick runs on Unix, Windows, Windows NT, Macintosh, and VMS. The Utah Raster Toolkit serves a lot of the same purpose as Netpbm, but without the emphasis on format conversions. This package is based on the RLE format, which you can convert to and from the Netpbm formats. http://www.cs.utah.edu/research/projects/alpha1/urt.html gives some information on the Utah Raster Toolkit, but does not tell where to get it. There are some Netpbm-like graphics tools distributed by the Army High Performance Computing Research Center at http://www.arc.umn.edu/gvl-software/media-tools.html. These operate directly on non-Netpbm format images, so they aren't included in the Netpbm package. However, you can use them with any image format by using the Netpbm format converters. Ivtools is a suite of free X Windows drawing editors for Postscript, Tex, and web graphics production, as well as an embeddable and extendable vector graphic shell. It uses the Netpbm facilities. See http://www.ivtools.org. Ilib is a C subroutine library with functions for adding text to an image (as you might do at a higher level with Pbmtext, Pnmcomp, etc.). It works with Netpbm input and output. Find it at <http://www.radix.net/~cknudsen/Ilib>. Netpbm also includes character drawing functions in the Libppm library, but they do not have as fancy font capabilities (see Ppmlabel for an example of use of the Netpbm character drawing functions). pnm2ppa converts to HP's "Winprinter" format (for HP 710, 720, 820, 1000, etc). It is a superset of Netpbm's pbmtoppa and handles, notably, color. However, it is more of a printer driver than a Netpbm-style primitive graphics building block. See <http://sourceforge.net/project/?group_id=1322>. HISTORY ------- See the file HISTORY. MORE INFORMATION ---------------- A good place to start for information about the wide world of computer graphics is http://www.faqs.org/faqs/graphics/ . COPYRIGHTS ---------- See the file COPYRIGHT.